GetFolderItem Function

Used to access an item in a folder (directory).

Syntax

result = GetFolderItem( path, [pathMode] )

Parameters
path	String	Empty string or path.Ordinarily, path is the name of a document.
pathMode (Optional)	Class	FolderItem class constant, PathTypeAbsolute, PathTypeShell, or PathTypeURL, indicating whether the path is a Shell path, an "ordinary" path, or path in the form of a URL. If you pass a Shell path, it must be an absolute path. If not, an UnsupportedFormatException will result. See the ShellPath property of the FolderItem class for information about shell paths. If you pass FolderItem.PathTypeURL, it must begin with "file:///".

Notes

The GetFolderItem function creates a FolderItem object for a specific item (application, document, or folder). GetFolderItem can be passed a file name for a specific item or an empty string. If you want to access an item via an absolute path, use the Volume function and the Child method of the FolderItem class.

If you intend to open an existing file with GetFolderItem, you should check the Exists property of the FolderItem to be sure that the file actually exists before accessing that FolderItem's properties.

Passing an empty string returns a FolderItem representing the folder the project is in. If you haven't saved the project, it returns the folder the REALbasic application is in.

For Mac OS X Mach-O applications, GetFolderItem returns the FolderItem for the directory containing the bundle instead of a FolderItem inside of the bundle.

GetFolderItem automatically resolves aliases when filename represents an alias. To prevent this, use GetTrueFolderItem.

Examples

This example displays the name of the folder that contains the REALbasic project in a message box.

Dim currentFolder as FolderItem
currentFolder=GetFolderItem ("")
MsgBox currentFolder.name

The following example uses the Child method of the FolderItem class to get an item within the current directory:

Dim f as FolderItem
f=GetFolderItem("Project Templates")

The following example uses the Parent property of the FolderItem class to get the parent directory for the directory that contains the application:

Dim f as FolderItem
f=GetFolderItem("").Parent

The following example opens a TIFF file in the same folder as the application (or the same folder as REALbasic if run from the IDE) and uses it as the background image ("backdrop") for a Canvas control:

Dim f as FolderItem
f=GetFolderItem ("Zippy.tif")
If f.exists then
Canvas1.backdrop=f.OpenAsPicture
end if

To get a reference using an absolute path, construct it using the Volume function and the Child method of the FolderItem class:. The example uses a Try block to handle the exception if the path is invalid.

Dim f as FolderItem
Try
f= Volume(0).Child("Documents").Child("Schedule")
Catch Err as NilObjectException
MsgBox "The path is invalid!"
End Try